/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @addtogroup OHAudioSuite
 * @{
 *
 * @brief 提供音频编创相关C接口定义。
 *
 * @syscap SystemCapability.Multimedia.Audio.SuiteEngine
 *
 * @since 22
 * @version 1.0
 */
/**
 * @file native_audio_suite_base.h
 *
 * @brief 声明音频编创相关底层数据结构。
 *
 * @library libohaudiosuite.so
 * @syscap SystemCapability.Multimedia.Audio.SuiteEngine
 * @kit AudioKit
 * @include <ohaudiosuite/native_audio_suite_base.h>
 * @since 22
 * @version 1.0
 */
#ifndef NATIVE_AUDIO_SUITE_BASE_H
#define NATIVE_AUDIO_SUITE_BASE_H
#include <stdint.h>
#include "multimedia/native_audio_channel_layout.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
 * @brief 定义音频编创节点类型。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 输入节点，支持从应用程序获取音频数据。
     *
     * @since 22
     */
    INPUT_NODE_TYPE_DEFAULT = 1,
    /**
     * @brief 输出节点，支持向应用程序提供音频数据。
     *
     * @since 22
     */
    OUTPUT_NODE_TYPE_DEFAULT = 101,
    /**
     * @brief 均衡器效果节点。
     * 均衡器效果节点输出的音频格式如下：\n
     * 采样率：48000Hz。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_S16LE。\n
     * 声道数：2。
     *
     * @since 22
     */
    EFFECT_NODE_TYPE_EQUALIZER = 201,
    /**
     * @brief 降噪效果节点。
     * 降噪效果节点输出的音频格式如下：\n
     * 采样率：16000Hz。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_S16LE。\n
     * 声道数：1。
     *
     * @since 22
     */
    EFFECT_NODE_TYPE_NOISE_REDUCTION = 202,
    /**
     * @brief 声场效果节点。
     * 声场效果节点支持的声场类型：{@link OH_SoundFieldType}。\n
     * 声场效果节点输出的音频格式如下：\n
     * 采样率：48000Hz。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_S16LE。\n
     * 声道数：2。
     *
     * @since 22
     */
    EFFECT_NODE_TYPE_SOUND_FIELD = 203,
    /**
     * @brief 音源分离效果节点。
     * 音源分离效果节点只能连接输出节点。\n
     * 音源分离效果节点输出的音频格式如下：\n
     * 采样率：48000Hz。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_F32LE。\n
     * 声道数：4（前2个声道用于人声，后2个声道用于伴奏）。\n
     *
     * @since 22
     */
    EFFECT_MULTII_OUTPUT_NODE_TYPE_AUDIO_SEPARATION = 204,
    /**
     * @brief 声音美化效果节点。
     * 声音美化效果节点支持的声音美化类型：{@link OH_VoiceBeautifierType}。\n
     * 声音美化效果节点输出的音频格式如下：\n
     * 采样率：48000Hz。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_S16LE。\n
     * 声道数：2。
     *
     * @since 22
     */
    EFFECT_NODE_TYPE_VOICE_BEAUTIFIER = 205,
    /**
     * @brief 环境效果节点。
     * 环境效果节点输出的音频格式如下：\n
     * 采样率：48000Hz。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_S16LE。\n
     * 声道数：2。
     *
     * @since 22
     */
    EFFECT_NODE_TYPE_ENVIRONMENT_EFFECT = 206,
    /**
     * @brief 混音效果节点。
     * 混音效果节点输出的音频格式如下：\n
     * 采样率：{@link OH_Audio_SampleRate}。\n
     * 采样格式：{@link OH_Audio_SampleFormat}.AUDIO_SAMPLE_F32LE。\n
     * 声道数：2。
     *
     * @since 22
     */
    EFFECT_NODE_TYPE_AUDIO_MIXER = 207,
} OH_AudioNode_Type;
/**
 * @brief 定义音频编创管线工作模式。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 编辑模式，管线处于该工作模式下可创建多种效果节点进行音频处理。
     *
     * @since 22
     */
    AUDIOSUITE_PIPELINE_EDIT_MODE = 1,
    /**
     * @brief 实时渲染模式，即在音频处理过程中实时播放已处理的音频。\n
     * 实时渲染模式下，管线仅支持均衡器效果处理。
     *
     * @since 22
     */
    AUDIOSUITE_PIPELINE_REALTIME_MODE = 2,
} OH_AudioSuite_PipelineWorkMode;
/**
 * @brief 定义音频编创管线运行状态。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 管线处于停止状态。
     *
     * @since 22
     */
    AUDIOSUITE_PIPELINE_STOPPED = 1,
    /**
     * @brief 管线处于运行状态。
     *
     * @since 22
     */
    AUDIOSUITE_PIPELINE_RUNNING = 2,
} OH_AudioSuite_PipelineState;
/**
 * @brief 音频编创错误码。
 *
 * @since 22
 */
typedef enum {
    /**
     * @error 调用成功。
     *
     * @since 22
     */
    AUDIOSUITE_SUCCESS = 0,
    /**
     * @error 输入参数无效。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_INVALID_PARAM = 1,
    /**
     * @error 非法状态。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_INVALID_STATE = 2,
    /**
     * @error 系统通用错误。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_SYSTEM = 3,
    /**
     * @error 不支持的音频格式，如不支持的编码类型、采样格式等。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_UNSUPPORTED_FORMAT = 4,
    /**
     * @error 引擎不存在。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_ENGINE_NOT_EXIST = 5,
    /**
     * @error 管线不存在。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_PIPELINE_NOT_EXIST = 6,
    /**
     * @error 节点不存在。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_NODE_NOT_EXIST = 7,
    /**
     * @error 节点之间不支持连接。
     *
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_UNSUPPORTED_CONNECT = 8,
    /**
     * @error 不支持的操作。例如，效果节点不支持设置音频格式。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_UNSUPPORTED_OPERATION = 9,
    /**
     * @error 创建管线或者节点超过系统最大数量限制。具体情况如下：\n
     * 引擎最多支持创建10条管线（其中，实时渲染管线最多创建1条）。\n
     * 每一个管线中，输入节点不超过5个，输出节点不超过1个，
     * 混音节点不超过3个，音源分离节点不超过1个，其余效果节点不超过5个。
     * @since 22
     */
    AUDIOSUITE_ERROR_CREATED_EXCEED_SYSTEM_LIMITS = 10,
    /**
     * @error 参数缺少必要参数。例如，输入节点未设置回调函数、输出节点未设置音频格式。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_REQUIRED_PARAMETERS_MISSING = 11,
    /**
     * @error 操作超时。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_TIMEOUT = 12,
    /**
     * @error 内存申请失败。
     *
     * @since 22
     */
    AUDIOSUITE_ERROR_MEMORY_ALLOC_FAILED = 13,
} OH_AudioSuite_Result;

/**
 * @brief 定义音频编创节点音频流的位深度。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief Unsigned 8位。
     *
     * @since 22
     */
    AUDIO_SAMPLE_U8 = 0,
    /**
     * @brief Short 16位小端。
     *
     * @since 22
     */
    AUDIO_SAMPLE_S16LE = 1,
    /**
     * @brief Short 24位小端。
     *
     * @since 22
     */
    AUDIO_SAMPLE_S24LE = 2,
    /**
     * @brief Short 32位小端。
     *
     * @since 22
     */
    AUDIO_SAMPLE_S32LE = 3,
    /**
     * @brief Float 32位小端。
     *
     * @since 22
     */
    AUDIO_SAMPLE_F32LE = 4,
} OH_Audio_SampleFormat;

/**
 * @brief 定义音频流编码类型。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief PCM编码。
     *
     * @since 22
     */
    AUDIO_ENCODING_TYPE_RAW = 0,
} OH_Audio_EncodingType;

/**
 * @brief 定义音频采样率。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 采样率8kHz。
     * @since 22
     */
    SAMPLE_RATE_8000 = 8000,
    /**
     * @brief 采样率11.025kHz。
     * @since 22
     */
    SAMPLE_RATE_11025 = 11025,
    /**
     * @brief 采样率12kHz。
     * @since 22
     */
    SAMPLE_RATE_12000 = 12000,
    /**
     * @brief 采样率16kHz。
     * @since 22
     */
    SAMPLE_RATE_16000 = 16000,
    /**
     * @brief 采样率22.05kHz。
     * @since 22
     */
    SAMPLE_RATE_22050 = 22050,
    /**
     * @brief 采样率24kHz。
     * @since 22
     */
    SAMPLE_RATE_24000 = 24000,
    /**
     * @brief 采样率32kHz。
     * @since 22
     */
    SAMPLE_RATE_32000 = 32000,
    /**
     * @brief 采样率44.1kHz。
     * @since 22
     */
    SAMPLE_RATE_44100 = 44100,
    /**
     * @brief 采样率48kHz。
     * @since 22
     */
    SAMPLE_RATE_48000 = 48000,
    /**
     * @brief 采样率64kHz。
     * @since 22
     */
    SAMPLE_RATE_64000 = 64000,
    /**
     * @brief 采样率88.2kHz。
     * @since 22
     */
    SAMPLE_RATE_88200 = 88200,
    /**
     * @brief 采样率96kHz。
     * @since 22
     */
    SAMPLE_RATE_96000 = 96000,
    /**
     * @brief 采样率176.4kHz。
     * @since 22
     */
    SAMPLE_RATE_176400 = 176400,
    /**
     * @brief 采样率192kHz。
     * @since 22
     */
    SAMPLE_RATE_192000 = 192000
} OH_Audio_SampleRate;

/**
 * @brief 定义音频编创的音频流信息，用于描述基本音频格式。
 *
 * @since 22
 */
typedef struct OH_AudioFormat {
    /**
     * @brief 音频流采样率。
     *
     * @since 22
     */
    OH_Audio_SampleRate samplingRate;
    /**
     * @brief 音频流声道布局，当前只支持CH_LAYOUT_MONO 和 CH_LAYOUT_STEREO。
     *
     * @since 22
     */
    OH_AudioChannelLayout channelLayout;
    /**
     * @brief 音频流声道个数，当前只支持1声道和2声道。
     *
     * @since 22
     */
    uint32_t channelCount;
    /**
     * @brief 音频流编码类型。
     *
     * @since 22
     */
    OH_Audio_EncodingType encodingType;
    /**
     * @brief 音频流采样格式。
     *
     * @since 22
     */
    OH_Audio_SampleFormat sampleFormat;
} OH_AudioFormat;

/**
 * @brief 定义多路输出渲染接口的输入数据描述。
 *
 * 当管线中存在多输出效果节点时，通过多输出渲染接口获取处理过后的音频数据。
 *
 * @since 22
 */
typedef struct OH_AudioDataArray {
    /**
     * @brief 需要输出的音频数据地址。
     *
     * @since 22
     */
    void **audioDataArray;
    /**
     * @brief 音频数组大小。
     *
     * @since 22
     */
    int32_t arraySize;
    /**
     * @brief audioDataArray数组中地址的内存大小（单位为字节），
     * 应确保每个地址均具有requestFrameSize字节个大小。
     *
     * @since 22
     */
    int32_t requestFrameSize;
} OH_AudioDataArray;

/**
 * @brief 定义音频编创声场效果节点的效果模式。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 前置声场效果。
     *
     * @since 22
     */
    SOUND_FIELD_FRONT_FACING = 1,
    /**
     * @brief 宏大声场效果。
     *
     * @since 22
     */
    SOUND_FIELD_GRAND = 2,
    /**
     * @brief 聆听声场效果。
     *
     * @since 22
     */
    SOUND_FIELD_NEAR = 3,
    /**
     * @brief 宽广声场效果。
     *
     * @since 22
     */
    SOUND_FIELD_WIDE = 4,
} OH_SoundFieldType;

/**
 * @brief 定义音频编创环境效果节点的模式。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 环境节点效果为广播。
     *
     * @since 22
     */
    ENVIRONMENT_TYPE_BROADCAST = 1,
    /**
     * @brief 环境节点效果为电话听筒。
     *
     * @since 22
     */
    ENVIRONMENT_TYPE_EARPIECE = 2,
    /**
     * @brief 环境节点效果为水下。
     *
     * @since 22
     */
    ENVIRONMENT_TYPE_UNDERWATER = 3,
    /**
     * @brief 环境节点效果为留声机。
     *
     * @since 22
     */
    ENVIRONMENT_TYPE_GRAMOPHONE = 4
} OH_EnvironmentType;

/**
 * @brief 定义音频编创美化效果节点模式。
 *
 * @since 22
 */
typedef enum {
    /**
     * @brief 声音美化节点效果为清澈。
     *
     * @since 22
     */
    VOICE_BEAUTIFIER_TYPE_CLEAR = 1,
    /**
     * @brief 声音美化节点效果为剧场。
     *
     * @since 22
     */
    VOICE_BEAUTIFIER_TYPE_THEATRE = 2,
    /**
     * @brief 声音美化节点效果为CD。
     *
     * @since 22
     */
    VOICE_BEAUTIFIER_TYPE_CD = 3,
    /**
     * @brief 声音美化节点效果为录音棚。
     *
     * @since 22
     */
    VOICE_BEAUTIFIER_TYPE_RECORDING_STUDIO = 4
} OH_VoiceBeautifierType;

/**
 * @brief 定义均衡器频带数量为10个。
 *
 * @since 22
 */
#define EQUALIZER_BAND_NUM (10)

/**
 * @brief 定义音频编创均衡器效果节点配置参数。
 *
 * @since 22
 */
typedef struct OH_EqualizerFrequencyBandGains {
    /**
     * @brief 均衡器频带增益配置，EQUALIZER_BAND_NUM为10，输入范围为[-10, 10]，单位为dB（分贝）。\n
     * 频带：31Hz、62Hz、125Hz、250Hz、500Hz、1kHz、2kHz、4kHz、8kHz、16kHz。
     *
     * @since 22
    */
    int32_t gains[EQUALIZER_BAND_NUM];
} OH_EqualizerFrequencyBandGains;

/**
 * @brief 默认均衡器频带增益效果。\n
 * 各频带增益：{0, 0, 0, 0, 0, 0, 0, 0, 0, 0}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_DEFAULT;

/**
 * @brief 均衡器节点内置民谣效果。\n
 * 各频带增益：{3, 5, 2, -4, 1, 2, -3, 1, 4, 5}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_BALLADS;

/**
 * @brief 均衡器节点内置中国风效果。\n
 * 各频带增益：{0, 0, 2, 0, 0, 4, 4, 2, 2, 5}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_CHINESE_STYLE;

/**
 * @brief 均衡器节点内置古典效果。\n
 * 各频带增益：{2, 3, 2, 1, 0, 0, -5, -5, -5, -6}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_CLASSICAL;

/**
 * @brief 均衡器节点内置舞曲效果。\n
 * 各频带增益：{4, 3, 2, -3, 0, 0, 5, 4, 2, 0}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_DANCE_MUSIC;

/**
 * @brief 均衡器节点内置爵士效果。\n
 * 各频带增益：{2, 0, 2, 3, 6, 5, -1, 3, 4, 4}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_JAZZ;

/**
 * @brief 均衡器节点内置流行效果。\n
 * 各频带增益：{5, 2, 1, -1, -5, -5, -2, 1, 2, 4}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_POP;

/**
 * @brief 均衡器节点内置R&B效果。\n
 * 各频带增益：{1, 4, 5, 3, -2, -2, 2, 3, 5, 5}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_RB;

/**
 * @brief 均衡器节点内置摇滚效果。\n
 * 各频带增益：{6, 4, 4, 2, 0, 1, 3, 3, 5, 4}。
 *
 * @since 22
 */
extern const OH_EqualizerFrequencyBandGains OH_EQUALIZER_PARAM_ROCK;

/**
 * @brief 声明音频编创引擎，用来管理音频编创管线。
 *
 * @since 22
 */
typedef struct OH_AudioSuiteEngineStruct OH_AudioSuiteEngine;

/**
 * @brief 声明音频编创引擎，用来管理音频编创节点。
 *
 * @since 22
 */
typedef struct OH_AudioSuitePipelineStruct OH_AudioSuitePipeline;

/**
 * @brief 声明音频编创节点，用于描述音频编创节点实例。
 *
 * @since 22
 */
typedef struct OH_AudioNodeStruct OH_AudioNode;

/**
 * @brief 声明音频编创节点的构造器。\n
 * 构造器实例通常用来设置音频流属性和创建音频流。
 *
 * @since 22
 */
typedef struct OH_AudioNodeBuilderStruct OH_AudioNodeBuilder;

#ifdef __cplusplus
}
#endif
/** @} */
#endif // NATIVE_AUDIO_SUITE_BASE_H